home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpmodule.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  6.3 KB  |  168 lines
  1. <refentry id="libgimp-gimpmodule" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpmodule</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpmodule</refname><refpurpose>Common definitions for creating a pluggable GIMP module.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. enum        <link linkend="GimpModuleStatus">GimpModuleStatus</link>;
  18. struct      <link linkend="GimpModuleInfo">GimpModuleInfo</link>;
  19. <link linkend="GimpModuleStatus">GimpModuleStatus</link> (<link linkend="GimpModuleInitFunc">*GimpModuleInitFunc</link>)      (<link linkend="GimpModuleInfo">GimpModuleInfo</link> **module_info);
  20. void        (<link linkend="GimpModuleCompletedCB">*GimpModuleCompletedCB</link>)        (<link linkend="gpointer">gpointer</link> completed_data);
  21. void        (<link linkend="GimpModuleUnloadFunc">*GimpModuleUnloadFunc</link>)         (<link linkend="gpointer">gpointer</link> shutdown_data,
  22.                                              <link linkend="GimpModuleCompletedCB">GimpModuleCompletedCB</link> completed_cb,
  23.                                              <link linkend="gpointer">gpointer</link> completed_data);
  24. </synopsis>
  25. </refsynopsisdiv>
  26.  
  27.  
  28.  
  29.  
  30.  
  31. <refsect1>
  32. <title>Description</title>
  33. <para>
  34. Common definitions for creating a pluggable GIMP module.
  35.  
  36. </para>
  37. </refsect1>
  38.  
  39. <refsect1>
  40. <title>Details</title>
  41. <refsect2>
  42. <title><anchor id="GimpModuleStatus">enum GimpModuleStatus</title>
  43. <programlisting>typedef enum
  44. {
  45.   GIMP_MODULE_OK,
  46.   GIMP_MODULE_UNLOAD
  47. } GimpModuleStatus;
  48. </programlisting>
  49. <para>
  50.  
  51. </para></refsect2>
  52. <refsect2>
  53. <title><anchor id="GimpModuleInfo">struct GimpModuleInfo</title>
  54. <programlisting>struct GimpModuleInfo
  55. {
  56.   gpointer     shutdown_data;
  57.  
  58.   const gchar *purpose;
  59.   const gchar *author;
  60.   const gchar *version;
  61.   const gchar *copyright;
  62.   const gchar *date;
  63. };
  64. </programlisting>
  65. <para>
  66.  
  67. </para></refsect2>
  68. <refsect2>
  69. <title><anchor id="GimpModuleInitFunc">GimpModuleInitFunc ()</title>
  70. <programlisting><link linkend="GimpModuleStatus">GimpModuleStatus</link> (*GimpModuleInitFunc)      (<link linkend="GimpModuleInfo">GimpModuleInfo</link> **module_info);</programlisting>
  71. <para>
  72. GIMP modules should <link linkend="G-MODULE-EXPORT-CAPS">G_MODULE_EXPORT</link> a function named "module_init"
  73. of this type.
  74. </para>
  75. <para>
  76. The "module_init" function is called by the GIMP at startup,
  77. and should return either <link linkend="GIMP-MODULE-OK-CAPS">GIMP_MODULE_OK</link> if it sucessfully initialised or
  78. <link linkend="GIMP-MODULE-UNLOAD-CAPS">GIMP_MODULE_UNLOAD</link> if the module failed to hook whatever functions
  79. it wanted.  <link linkend="GIMP-MODULE-UNLOAD-CAPS">GIMP_MODULE_UNLOAD</link> causes the module to be closed, so
  80. the module must not have registered any internal functions or given
  81. out pointers to its data to anyone.
  82. </para>
  83. <para>
  84. If the module returns <link linkend="GIMP-MODULE-OK-CAPS">GIMP_MODULE_OK</link>, it should also return a
  85. <link linkend="GimpModuleInfo">GimpModuleInfo</link> structure describing itself.
  86. </para><informaltable pgwide=1 frame="none" role="params">
  87. <tgroup cols="2">
  88. <colspec colwidth="2*">
  89. <colspec colwidth="8*">
  90. <tbody>
  91. <row><entry align="right"><parameter>module_info</parameter> :</entry>
  92. <entry>Returns the <link linkend="GimpModuleInfo">GimpModuleInfo</link> desribing the module.
  93. </entry></row>
  94. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>A <link linkend="GimpModuleStatus">GimpModuleStatus</link> value indicating success.
  95.  
  96.  
  97. </entry></row>
  98. </tbody></tgroup></informaltable></refsect2>
  99. <refsect2>
  100. <title><anchor id="GimpModuleCompletedCB">GimpModuleCompletedCB ()</title>
  101. <programlisting>void        (*GimpModuleCompletedCB)        (<link linkend="gpointer">gpointer</link> completed_data);</programlisting>
  102. <para>
  103. The type of the <parameter>completed_cb</parameter> passed to the "module_unload" function
  104. (see below).
  105. </para><informaltable pgwide=1 frame="none" role="params">
  106. <tgroup cols="2">
  107. <colspec colwidth="2*">
  108. <colspec colwidth="8*">
  109. <tbody>
  110. <row><entry align="right"><parameter>completed_data</parameter> :</entry>
  111. <entry><para>
  112. Must be the <parameter>completed_data</parameter> pointer provided by the "module_unload"
  113. function.
  114. </para>
  115.  
  116.  
  117. </entry></row>
  118. </tbody></tgroup></informaltable></refsect2>
  119. <refsect2>
  120. <title><anchor id="GimpModuleUnloadFunc">GimpModuleUnloadFunc ()</title>
  121. <programlisting>void        (*GimpModuleUnloadFunc)         (<link linkend="gpointer">gpointer</link> shutdown_data,
  122.                                              <link linkend="GimpModuleCompletedCB">GimpModuleCompletedCB</link> completed_cb,
  123.                                              <link linkend="gpointer">gpointer</link> completed_data);</programlisting>
  124. <para>
  125. If GIMP modules want to allow themselves to be unloaded, they
  126. should <link linkend="G-MODULE-EXPORT-CAPS">G_MODULE_EXPORT</link> a function named "module_unload" of
  127. this type.
  128. </para>
  129. <para>
  130. GIMP calls the "module_unload" unload request function to ask
  131. a module to prepare itself to be unloaded.  It is called with the
  132. value of <parameter>shutdown_data</parameter> supplied in the <link linkend="GimpModuleInfo">GimpModuleInfo</link> struct.
  133. The module should ensure that none of its code or data are being
  134. used, and then call the supplied <parameter>completed_cb</parameter> callback function with
  135. the <parameter>completed_data</parameter> provided.  Typically the shutdown request function
  136. will queue de-registration activities then return.  Only when the
  137. de-registration has finished should the <parameter>completed_cb</parameter> be invoked.
  138. </para><informaltable pgwide=1 frame="none" role="params">
  139. <tgroup cols="2">
  140. <colspec colwidth="2*">
  141. <colspec colwidth="8*">
  142. <tbody>
  143. <row><entry align="right"><parameter>shutdown_data</parameter> :</entry>
  144. <entry>The <parameter>shutdown_data</parameter> supplied in the <link linkend="GimpModuleInfo">GimpModuleInfo</link> struct.
  145. </entry></row>
  146. <row><entry align="right"><parameter>completed_cb</parameter> :</entry>
  147. <entry>The function to call after successful unload.
  148. </entry></row>
  149. <row><entry align="right"><parameter>completed_data</parameter> :</entry>
  150. <entry>Has to be passed to the <parameter>completed_cb</parameter>.
  151.  
  152.  
  153. </entry></row>
  154. </tbody></tgroup></informaltable></refsect2>
  155.  
  156. </refsect1>
  157.  
  158.  
  159.  
  160. <refsect1>
  161. <title>See Also</title>
  162. <para>
  163. <link linkend="GModule">GModule</link>
  164. </para>
  165. </refsect1>
  166.  
  167. </refentry>
  168.